# API响应工具
from flask import jsonify
from typing import Any, Dict, List, Optional, Union

def response_success(data: Any = None, msg: str = "success", code: int = 200):
    """
    返回成功响应
    :param data: 响应数据
    :param msg: 响应消息，默认为"success"
    :param code: 响应状态码，默认为200
    :return: JSON响应
    """
    response_data = {
        'code': code,
        'data': data,
        'msg': msg
    }
    return jsonify(response_data), code

def response_fail(msg: str = "error", code: int = 400, data: Any = None):
    """
    返回失败响应
    :param msg: 错误消息，默认为"error"
    :param code: 错误状态码，默认为400
    :param data: 错误数据，可选
    :return: JSON响应
    """
    response_data = {
        'code': code,
        'data': data,
        'msg': msg
    }
    return jsonify(response_data), code

def response_page(data: List[Dict], page: int = 1, per_page: int = 10, 
                 total: int = 0, msg: str = "success", code: int = 200):
    """
    返回分页响应
    :param data: 数据列表
    :param page: 当前页码，默认为1
    :param per_page: 每页数量，默认为10
    :param total: 总记录数
    :param msg: 响应消息，默认为"success"
    :param code: 响应状态码，默认为200
    :return: JSON响应
    """
    response_data = {
        'code': code,
        'data': {
            'items': data,
            'pagination': {
                'page': page,
                'per_page': per_page,
                'total': total,
                'pages': (total + per_page - 1) // per_page
            }
        },
        'msg': msg
    }
    return jsonify(response_data), code

def response_created(data: Any = None, msg: str = "created successfully"):
    """
    返回创建成功响应
    :param data: 创建的数据
    :param msg: 响应消息，默认为"created successfully"
    :return: JSON响应
    """
    return response_success(data=data, msg=msg, code=201)

def response_updated(data: Any = None, msg: str = "updated successfully"):
    """
    返回更新成功响应
    :param data: 更新的数据
    :param msg: 响应消息，默认为"updated successfully"
    :return: JSON响应
    """
    return response_success(data=data, msg=msg, code=200)

def response_deleted(msg: str = "deleted successfully"):
    """
    返回删除成功响应
    :param msg: 响应消息，默认为"deleted successfully"
    :return: JSON响应
    """
    return response_success(data=None, msg=msg, code=204)

def response_unauthorized(msg: str = "unauthorized"):
    """
    返回未授权响应
    :param msg: 错误消息，默认为"unauthorized"
    :return: JSON响应
    """
    return response_fail(msg=msg, code=401)

def response_forbidden(msg: str = "forbidden"):
    """
    返回禁止访问响应
    :param msg: 错误消息，默认为"forbidden"
    :return: JSON响应
    """
    return response_fail(msg=msg, code=403)

def response_not_found(msg: str = "not found"):
    """
    返回未找到响应
    :param msg: 错误消息，默认为"not found"
    :return: JSON响应
    """
    return response_fail(msg=msg, code=404)

def response_validation_error(errors: Dict[str, List[str]], msg: str = "validation error"):
    """
    返回验证错误响应
    :param errors: 验证错误字典
    :param msg: 错误消息，默认为"validation error"
    :return: JSON响应
    """
    return response_fail(msg=msg, code=422, data=errors)

def response_server_error(msg: str = "internal server error"):
    """
    返回服务器错误响应
    :param msg: 错误消息，默认为"internal server error"
    :return: JSON响应
    """
    return response_fail(msg=msg, code=500)